Authentication & API Setup

To interact with AthenaHealth’s API, Bookadoc uses OAuth 2.0, a secure authorization protocol that enables safe access to AthenaHealth’s services. This authentication ensures that only authorized systems can retrieve and modify appointment data, patient records, and provider schedules.

AthenaHealth requires API clients to use Client Credentials Grant Flow, which involves obtaining an access token before making API requests.

---

OAuth 2.0 Authentication Process

The authentication process follows these steps:

1. Obtain Access Token

Bookadoc sends a request to AthenaHealth’s authentication endpoint using the client’s API credentials.

API Endpoint

POST /oauth2/v1/token

Request Headers

Content-Type: application/x-www-form-urlencoded
Authorization: Basic {Base64Encoded(client_id:client_secret)}

Request Body

grant_type=client_credentials
scope=athena/service/Athenanet.MDP.*

Successful Response Example

{
  "access_token": "eyJhbGciOiJIUz...",
  "token_type": "Bearer",
  "expires_in": 3600
}

• access_token: The token required for subsequent API requests.
• expires_in: The lifespan of the token (in seconds). After this period, a new token must be requested.

---

2. Use the Access Token

Once obtained, the access token must be included in the Authorization header of every API request.

Example Request (Fetching Open Appointments)

GET /v1/{practiceid}/appointments/open

Headers

Authorization: Bearer {access_token}
Content-Type: application/json

---

3. Token Expiry & Renewal

AthenaHealth’s access tokens are temporary and expire after one hour (3600 seconds). To ensure continuous access, Bookadoc currently handle token renewal by:

• Storing the token’s expiration time
• Requesting a new token when the previous one expires
• Avoiding unnecessary re-authentication when a valid token exists

---

Required Credentials

To authenticate with AthenaHealth, the following credentials must be configured:

Parameter	Description
client_id	Unique identifier for Bookadoc’s integration
client_secret	Secret key for authentication
practice_id	Identifier for the healthcare provider’s AthenaHealth instance

These credentials are securely stored and never exposed in client-side applications.

---

Error Handling in Authentication

If authentication fails, the API returns an error response. Bookadoc must handle these scenarios properly.

Common Authentication Errors

Error Code	Description	Resolution
401 Unauthorized	Invalid credentials or expired token	Ensure correct credentials and refresh token if expired
403 Forbidden	Insufficient permissions	Verify API scope and permissions
500 Internal Server Error	AthenaHealth service issue	Retry after some time

---

Security Best Practices

To ensure secure authentication:

• Store API credentials securely using environment variables.
• Rotate client credentials periodically to reduce security risks.
• Use HTTPS for all API requests to encrypt sensitive data.

---

Conclusion

Bookadoc authenticates with AthenaHealth using OAuth 2.0, obtaining an access token to make secure API requests. The integration ensures smooth authentication handling, token renewal, and error management, allowing seamless access to appointment and patient data.

---